The present invention relates, in general, to design documentation, and more particularly to a method for maintaining design documentation together with software source code.
Development of a complex system typically proceeds in a hierarchical fashion from a general top level overview of the problem addressed through layers of more and more specific information until final design documentation is generated. Typically the highest level of documentation is a text description which defines the desired functionality of the system being designed. The text description is refined by adding diagrams, flow charts, block diagrams, and further text to provide layers of increasing detail until the system being designed is completely and explicitly defined.
The system may be implemented as entirely software, entirely as a new apparatus, or as a combination of apparatus together with controlling software. Typically the hardware portion is described using a hardware design language such as the well known VHSIC Hardware Design Language (VHDL) which can be automatically processed to produce working hardware. Similarly software can be described in terms of a high level object oriented language such as C++. The computer system which uses a language translator to compile the source language code into a computer program which is run on a computer system of some sort. For either type of design, and especially for designs which involve a hybrid of hardware and software, refinements and changes to the desired functionality must be made as the design proceeds. In addition, various design decisions must be documented for future reference. Typically this has been accomplished by use of a mechanism such as a comment field embedded within the source code of the language. A region of text is delineated in some fashion and passed to the language translator. Since the comment text is part of a comment, it is ignored as the language translator generates the executable form of the program. The language translator must be able to determine the start and end of comments so as to ignore the appropriate text. Each programming language defines a mechanism to accomplish this, typically by reserving one or more characters to delineate the comments. Accordingly text within a comment is limited to a predefined set of allowable characters. As a result information such as graphics, sound, and complex data structures cannot be conveniently included within a comment.
Typically more extensive design information was kept in separate files and called "documentation". Documentation is a written record of the problem definition and details about implementation in hardware and software. As the program changes over time the documentation must also be changed. Inaccurate or out of date documentation confuses or misdirects the developer causing inaccurate modifications and schedule overruns. Keeping the documentation in a separate file from the program itself often caused the developer to overlook revising the documentation when the program was changed.
One solution to this problem was to include the documentation into the same file as the program source code as a form of extended comment. One technique for accomplishing this is found in the paper titled "A PROGRAM DOCUMENTATION TOOL" by Robert Turner, pp. 87-89 of Technical Developments, Vol. 17, December 1992 published by Motorola, Inc., which is incorporated herein by reference made thereto. This paper describes a method for including documentation as comments into a source (program) file. The documentation is extracted from the source by a documentation extraction process and reformatted into a human readable form.
This method is limited in handling documentation for two reasons. In a typical design, the documentation is created before the source files. The documentation then guides and directs the developer in creating the source files. The described method requires the combining of the documentation into source files after the source file has been at least partially completed. This sequence readily leads to inaccurate or out of date documentation as before.
The second limitation is caused by the limited nature of the structure of a program source file. Documentation takes the form of text with different sizes and fonts, graphics, tables of contents, indexes, pictures, and even sound to capture the designer's thoughts and ideas. A source program file is limited to simple text files. In order to incorporate documentation in its varied forms, several complex functions are required to transform documentation into simple text files. Documentation transformed into a simple text file may include the marker text causing the language translators to try and parse the documentation as actual program language. Alternatively because of length, the encoded documentation may overflow the computer language translate program.
Another problem not addressed by the described method is encoding of the documentation. The process of encoding the documentation hinders the development process. As the developer is trying to create the hardware description language or program source file, the documentation that describes what should be done has been encoded losing most if not all of its use to the designer. This encoded documentation is little more than gibberish and complicates the developer's authoring process rather than aiding.
Such a method is inherently limited in handling all of the information generated by the documentation process. This information includes such things as text of different sizes and fonts, graphics, tables of contents, indexes, pictures, and even sound so as to better capture the programmer's thoughts and ideas. There is a need for a program documentation tool which allows free incorporation of any type of documentation into a single file such that the documentation in whatever form required can be modified along with the source code which actually generates the program. Such a method should include the capability for using such tools as data flow diagrams and their associated properties, allow incorporation of multiple programs within a single file, and preferably allow incorporation of fragments of programs in whatever order is convenient for documentation rather than that required for a language translator.